﻿#region header

//  ***************************************************************************
// *                                LICENSE
//  ***************************************************************************
//  * "Haplous" .NET Simple 2D Game Framework
//  * 
//  * Copyright © Jonathan Evans 2014-2014
//  * 
//  * This program is free software; you can redistribute it and/or
//  * modify it under the terms of the GNU General Public License
//  * as published by the Free Software Foundation; either version 2
//  * of the License, or (at your option) any later version.
//  * 
//  * This program is distributed in the hope that it will be useful,
//  * but WITHOUT ANY WARRANTY; without even the implied warranty of
//  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  * GNU General Public License for more details.
//  * 
//  * You should have received a copy of the GNU General Public License
//  * along with this program; if not, write to the Free Software
//  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
//  * 
//  ***************************************************************************
//  * 
//  * Contact: opencollar@googlemail.com
//  * 
//  * Website: http://haplous.codeplex.com/
//  *
//  * NuGet:   http://www.nuget.org/packages/haplous/
//  *
//  * File:    Haplous/Haplous/SolidGraphicBlock.cs
//  *
//  ***************************************************************************

#endregion

using System.Diagnostics;
using System.Diagnostics.CodeAnalysis;

using JetBrains.Annotations;

namespace Haplous
{
    /// <summary>
    ///     The basic class for all visual elements in a game that have size, position and can interact with other elements.
    /// </summary>
    [SuppressMessage("Microsoft.Maintainability", "CA1501:AvoidExcessiveInheritance")]
    [SuppressMessage("Microsoft.Design", "CA1063:ImplementIDisposableCorrectly")]
    [DebuggerDisplay("SolidGraphicBlock: Name={Name}; Position={_position.X),{_position.Y); Size={_size.Width),{_size.Height)")]
    public abstract class SolidGraphicBlock : GraphicBlock, ISolidGraphicBlock
    {
        /// <summary>
        ///     Initializes a new instance of the <see cref="SolidGraphicBlock" /> class.
        /// </summary>
        /// <param name="game">
        ///     The game to which the class belongs.  The <paramref name="game" /> must not be
        ///     <see langword="null" />.
        /// </param>
        /// <param name="name">A name that uniquely identifies this solid.</param>
        protected SolidGraphicBlock([NotNull] Game game, [NotNull] string name) : base(game, name)
        {}

        /// <summary>
        ///     Occurs when an item that is attempting to move is found to be in collision with this item.
        /// </summary>
        /// <param name="item">The item that is attempting to move.</param>
        /// <param name="oldPosition">The starting position of the item that has changed.</param>
        /// <param name="oldSize">The original size of the item that has changed.</param>
        /// <param name="newPosition">The proposed new position of the item that has changed.</param>
        /// <param name="newSize">The proposed new size of the item that has changed.</param>
        /// <returns>The outcome of the collision.</returns>
        /// <remarks>
        ///     The intention of this method is to allow the receiver to make a decision about, but not yet react, to an impact.
        ///     The reaction should occur when the <see cref="OnCollision" /> method is called.
        /// </remarks>
        public virtual OutcomeKind OnColliding([NotNull] SolidGraphicBlock item, [NotNull] PositionInt32 oldPosition, [NotNull] SizeInt32 oldSize, [NotNull] PositionInt32 newPosition,
                                               [NotNull] SizeInt32 newSize)
        {
            // By default all collisions are between hard inert objects - so no overlap allowed, but no consequences.
            return OutcomeKind.Bounce;
        }

        /// <summary>
        ///     Called when another element has moved and a collision has occurred.
        /// </summary>
        /// <param name="item">The item that has moved.</param>
        /// <param name="anticipatedOutcome">The anticipated outcome from the previous call to <see cref="OnColliding" />.</param>
        /// <remarks>This method is called to allow the recipient to react to the collision.</remarks>
        public virtual void OnCollision([NotNull] SolidGraphicBlock item, OutcomeKind anticipatedOutcome)
        {
            // By default, do nothing.
        }
    }

    /// <summary>
    ///     The ways in which a <see cref="SolidGraphicBlock" /> may react to a collision.
    /// </summary>
    public enum OutcomeKind
    {
        /// <summary>
        ///     There is no collision.
        /// </summary>
        None = 0,

        /// <summary>
        ///     The <see cref="SolidGraphicBlock">Solids</see> may not interact (the moving <see cref="SolidGraphicBlock" /> must
        ///     not overlap with the
        ///     other <see cref="SolidGraphicBlock" /> and its movement must be adjusted so this does not happen).
        /// </summary>
        /// <remarks>
        ///     In this case of this kind of collision the moving object will be moved as close as possible without
        ///     overlapping.
        /// </remarks>
        Bounce,

        /// <summary>
        ///     The <see cref="SolidGraphicBlock">Solids</see> are permitted to overlap - creation-order (within layers) and
        ///     layer-order will be used to determine how to render.
        /// </summary>
        Permitted,

        /// <summary>
        ///     The <see cref="SolidGraphicBlock">Solids</see> are permitted to overlap - an interaction will be triggered when the
        ///     movement has completed.
        /// </summary>
        Reactive
    }
}